Almathera Ten Pack 3: CDPD 3/Almathera Ten on Ten - Disc 3: CDPD3.iso/fish/726-750/743/megaed/megaed.doc

Text File | 1995-03-18 | 25KB | 610 lines

                                MegaEd v1.5i

                             T H E   M A N U A L


                                  CONTENTS

                   1. Introduction
                   2. General Features
                   3. Text Editing
                   4. Database, Formatting And Print Facilities
                   5. The MegaEd Macro Language
                   6. Arexx
                   7. Special Features
                   8. Trouble Shooting
                   9. Additional Info's



-------------------------------------------------------------------------
                             1. INTRODUCTION
-------------------------------------------------------------------------

What is MegaEd?

In short, MegaEd is an ordinary TextEd with lots of special features, like
build-in Text Oriented Database, own Macro Language and Arexx-port. To
give you a brief idea of the nice points about MegaEd as opposed to a
basic-texteditor here's a list of features:

- Functions to handle your text as database like Sort records, Trim,
  delete fields, Switch order of fields/indexreferences etc.
- Multiple ways of formatting print output, in cooperation with database
  functions like print on columns, as database labels, or with alinea/
  line formatting.
- All normal editing can be done either fully by keyboard or mouse.
- Arexx port
- Own macro language for use with or _without_ Arexx, command
  console for arexx-output/macro direct modus
- Fully configurable settings with function-key definitions.
- AutoIndention and Auto Keyword Indent (configurable)
- Lots of possibilties for programmers: Bracket {}()[] checking,
  Reformat whole sourcecodes according to keyword-indention,
  Compile, link and run directly from MegaEd (by pressing F-keys),
  fully programmable environment.
- Superfast scrolling with double-arrow gadgets, shift up/down and
  mega-scrollbar.
- keyboard/menu/mouseclicks macro recording
- flexible block/edit functions: perform actions on multiple blocks,
  (like 'Mark' in a database) shift block left/right, save multiple blocks.
- Auto NTSC/PAL detect, as well as Interlace.
- Full kick 1.2+ and 2.x compatability.
- inumerable powerfull options

Ofcourse there might also be some dark sides to MegaEd, which will be
discussed in the "Troubleshooting" section. For certain constraints on
distribution of this Ed, refer to the "Additional infos" section.

Running MegaEd:
Click on the icon or type the name. when running from a shell, an
optional path maybe specified to load straight away, like:

MEGAED DF1:SRC/

MegaEd doesn't need any diskbased librarys or devices to run. It only
tries to load a file called 'S:MegaEd.Startup' when present


-------------------------------------------------------------------------
                           2. GENERAL FEATURES
-------------------------------------------------------------------------

Functions described in this chapter won't need explanation for most users
but will be given a short description anyhow. Functions will be treated
as they can be found in the menus, although they can nearly all be reached
by keyboard, and some of them by clicking gadgets (or using Arexx).
Let us kick ass with the Project menu:

Load Text        Will load (using a filerequester) a _pure_ amiga textfile
                 into the buffer and erase any previous text. May load
                 odd-formatted texts, but texts containing binary will be
                 rejected.
Merge Text       Same as load, only will not erase previous text, but add
                 to the end of it.
Save Text        Writes text in Ascii format to disk.
Save Text As     Same, but with filerequest.
Clear Buffer     Enables you to empty the buffer.
Print            Writes text to PRT: or other device
Save and Quit    Leaves after saving correctly
Quit             Guess what..
About MegaEd     Shows some infos. Don't be offended by the additional infos
                 MegaEd may display.
Change Directory change default path without a filerequest.
Set Printer      allows you to set any device (like PRT:) as device
                 to print to. also asks for paperlenght etc.

IMPORTANT: If you change the diskpath, or enter directory's in the
filerequester, suply subdirectory's with an extra '/', otherwise
the requester takes it for a file (e.g 'dh0:s/' and not 'dh0:s').

Printing of texts is done simply by selecting Print. Changing
the output destination (default = PRT:) is done with Set Printer
Print will only dump the text, nothing special. If you
want the text to be outputted in pages, specify the page lenght (that
is, without the skipped part) with Settings/PageLenght (default = 68)
and the number of lines to be skipped at the end of each page (default
= 4) with Settings/PageSkip (thus obtaining default-A4-papersize of 72).

-------------------------------------------------------------------------
                              3. TEXT EDITING
-------------------------------------------------------------------------

Here we will discuss elementary editing functions, as found in the
Edit, Search, Line and Move menus.

In general some things are to be said about Line-Editing: All standard
keys are ofcourse supported (yes, backspace etc.), lines are limited to
500 characters for some reason, and scroll ahead as you edit. Difference
with other editors may be that the irritating 'drop-off-the-line' as
you move your cursor to end is disabled.

To mark one or more (!) blocks, hold down left-alt and select
the area with your mouse. Note that you may mark any number of
blocks in one go, and all editing functions will take effect
on all blocks (!).

Use Clear Marks to undo you selection, Mark All to select the whole
buffer as a block. Toggle Marks and Toggle mark line will clear
all blocks, and select all unselected text as a block.

Copy Blocks will copy the block to another buffer, Cut Blocks does the
same as Copy but removes the block from the buffer. Paste will put
the block in the other buffer back into the text at the cursor position
Delete just removes selected lines.

Print and Save Blocks will just do the same as Print and Save in the
project menu, only they take effect on the selected blocks.

Shift Blocks Left and Right will remove or add spaces (according to
Format/Settings/IndentSize) to the lines marked. very handy if you
change structure in your C/Pascal type programs with new {} BEGIN/END
blocks surrounding text already entered.

Find will move cursor and screen to first occurence of the sting entered.
If you want that string to be replaced, make sure the replace string
entered at Set Replace is not empty.
Find All will simply replace all occurences of the string through the
whole text without asking first.

Cut, Copy and Paste are also provided on line-basis: they operate only
on one entire line (very handy as you will notice). Wrong corrections
are easily Undone by pressing HELP. Centre will indeed centre the line
the cursor is currently on.

Moving around the text is easy with those arrow-gadgets provided on the
left of the screen (Start of Text, Page Up, Line Up, Line Down, Page
Down and End of Text respectively). All these are in the Move menu too
as well as some additional (Shift Left/Right/Up/Down).

last-minute-addition: a need was felt among the MegaEd users
that a scroll-bar would come in handy: this feature has been preliminary
implemented: pressing the left mouse button (to position the cursor),
holding it, and then touching the right one once turns the
text-editing gadget into one giant mega-scrollbar. try it!
note: the scrolling is pretty fast, but not fast enough as MegaEd
does not scroll small jumps, but refreshes the whole screen.
a cygnused lookalikescroll will featured in the next major update.


-------------------------------------------------------------------------
              4. DATABASE, FORMATTING AND PRINT FACILITIES
-------------------------------------------------------------------------

Printing with Wordpro Print makes a print that is correctly formatted
(splits lines between words when they're too long) with possible alinea-
starts, and blanks before second lines. Set Settings/AlineaSkip and
Settings/2ndLineSkip to the appropriate number of spaces (note: do
not enter a number, but the actual spaces!) and Settings/TextWidth
to the width of the text to print (and where to cut of). then select
Wordpro Print.

The other two print methods are only usefull in combination with a
database, so I'll treat that now:
First, let me state how databases are handled within MegaEd. Because of
MegaEd being a texted, Records are regarded as a line, and Fields are
sepated by a separator sign, which could be anything from a simple
comma to a complete sequence of characters. This concept thus enables
you to build database of a simple kind like addresses, disk and music
collections etc, and handle them like a normal database but still edit
with the ease of a texteditor. As an example, say you have edited
your addresslist with the following contents:

Mayor, J.; Downing street 10; London
Bush, G.; White House; Washington D.C.
Gorbatjov, M.; Kremlin; Moskou

... and more of these. Then, use Settings/Separator to tell MegaEd your
fields are divided by ';' (default = ,). Now you sort your long list
of addresses with Format/Sort, and remove eventual leading spaces
with Format/Trim (or better even, press the button...).
Following Things can be done with your database:

dBase Print:
Prints all in fixed format as labels: you get name, address etc. below
eachother. this is usefull for labels, but also a more database-like
overview. Even if you work with variable amounts of fields (say: 3/4)
the amount of lines for each record will still be the same (default = 6),
and not 6/7 (change this with Settings/RecordSize).

Columns Print:
This is the nicest of the print functions: it prints your database into
straight columns, without the separator. Just specify the amount of
columns you would like to have with Settings/Nr. of Fields (default = 3),
and the width of each column with Settings/Fieldwidth (default = 20).
And now here's the big trick: Entering nothing (that is: empty string)
at Settings/FieldWidth will tell MegaEd to calculate the best possible
width for each column automaticly. In our example, this would yield
the following output:

Mayor, J.     Downing street 10 London
Bush, G.      White House       Washington D.C.
Gorbatiov, M. Kremlin           Moskou

Switch:
Suppose you would like to sort on field #3, you would use
Settings/SwitchOrder to set how you would like to reorder your fields
(default = 123), so in this case you would use 312 (first, take field #3,
then #1, then #2), and select Format/Switch. note: switching takes
some processing-time, no large texts should be treated this way.

DelField:
This is usefull for making lists with one field crossed-out. Just enter
the the number of the field to be deleted at Settings/Fieldno., and
select Delfield.

Build Indention:
Rebuilt the indentstructure of your program, very handy if you often
change it. type something like:

main()         will become:   main()
{                             {
int a,b;                        int a,b;
if a==1                         if a==1
{                               {
b=2;                              b=2;
}                               }
}                             }

provided you defined {} as auto indent keywords. Automatic indent like
this while typing can be done by toggling Settings/AutoIndent on (= default).

Make Indexreference:
this is a complex feature. it allows you, if for example you
have a video database (original eh?) with a set of #'s behind each
entry specifying which tapes they're on:

mickey mouse, 3,56,14
donald duck, 8,14,34,37
rambo, 2,15,31,44,62

to have an overview generated automatically with each tape stating what's
on it: i.e.:

14        mickey mouse
        donald duck
15        rambo XIV
16        goofy's adventures
        minnie mouse
        documentary: the sexlife of snales
17        terminator VII

MegaEd will ask for the start and end entry, in this example this would
be 14 and 17. if your videobase ranges from 1 to 63, you may enter those.
Experiment with this function if you think you have a use for it. note
that it this is a slow function, as it needs to scan the whole buffer
over and over again.


-------------------------------------------------------------------------
                        5. THE MEGAED MACRO LANGUAGE
-------------------------------------------------------------------------

MegaEd has it's own macro language which serve five purposes:
- make MegaEd managable from Arexx
- enables you to write macro's
- makes compilation from the ed and similar features possible
- enable you to set defaults and do things at MegaEd startup
- lets you control MegaEd by a shell/direct modus

They can be invoked in four ways:
- by adding them to the S:MegaEd.Startup text file (just write a text
  file with a command on every line, put it in s:, and those will
  be executed every time you run MegaEd).
- by issueing them in an Arexx-program to the MEGAED host (see Chapt. 6).
- By Writing a macro-program for a function-key (Special/Make Program),
  and subsequently pressing that key whenever you like.
- by typing them from the MML (MegaEd macro language) command shell.

Now Follows an overview of commands (organised to usefullness):
Usefull for Macro's (and sometimes Arexx):

SAVE <filespec>          Saves buffer to disk
EXE <filespec+arg>       Executes Dos-command (needs c:run)
LOAD <filespec>          Loads buffer with file
BACK                     Puts editor screen back
FRONT                    Puts .. (i'm not gonna explain this)
WRITE <message>          Prints something on the status-line (no quotes)

Usefull for Arexx (and often macro's):

TOP                      Jumps to top of buffer
BOTTOM                   Jumps (ahem.. yes.. find out yourself)
LINE <nr>                Jumps to line specified
MAXLINE                  Returns number of lines (Arexx only)
CURSOR <pos>             Puts cursor on position
MAXCURSOR                Return lenght of current line (Arexx only)
DELETE                   Deletes current line
INSERT <string>          Inserts string at current line
TRIM                     Remove first spaces in buffer
SORT                     Sort buffer
SETREPLACE <string>      Sets replace string
FIND <string>            Moves cursor to first occurence of string
DELCHAR                  Deletes character at current position and
                         returns it's ascii value (Arexx only)
INSCHARS <string>        Inserts string at cursor (specifying an '#' with
                         a value, will insert an ascii (e.g. '#65' = 'A').
NOREFRESH                Disables refresh of screen (Arexx only)
REFRESH                  Enables screenrefresh and refreshes screen
RET                      Puts returnvalue of previous command in 'rc'

Usefull for MegaEd Startup:

PATH <diskpath>          Sets diskpath
PRINTER <device>         Sets device to print to (PRT:, PAR: etc.)
PAGESKIP <amount>        Sets Pageskip
PAGELEN <size>           Sets PageLenght (yawn..)
INDENT ON/OFF            Choose if you want AutoIndent to be on/off
                         (as default)
INDENTSTART <string>     Enter keyword you want to jump in at
INDENTEND <string>       As well as for the end of a block
SETIDENT <amount>        Amount of spaces you want to jump in (2/4/8 etc.)
DEF <funnr> <commands>   Define a macro (see example)
TITLE                    Toggles titlebar on/off (default = off).


Future versions of MegaEd will contain all editor commands as
Arexx-commands too.

An Example of a S:MegaEd.Startup file:

DEF 1 BACK; SAVE ram:x.s; EXE a68k ram:x.s
DEF 2 EXE blink ram:x.o
DEF 3 EXE ram:x; FRONT
PATH Dh0:src/
PAGELENGHT 68
PAGESKIP 4
WRITE Goodmorning
INDENT ON
INDENTSTART BEGIN { do if
INDENTEND END } end

Explanation:
First we define three function keys (F1-F3) with the following: (F1) editor
to back, write dummy file to ram and assemble it. Then if al went ok (F2)
to link the file from the ed, and (F3) to run it (could be all in one
macro too!). Note that, in macro's, commands are separated with a
semicolon.
Then, define our default load/save path to dh0:src, set some printer
settings, and output something nice. Enable the AutoIndent and Auto
Keyword Indent features, and define some places to build indents
for respectively Pascal, C and Arexx.


------------------------------------------------------------------------
                                6. AREXX
------------------------------------------------------------------------

MegaEd has an Arexx-port, which is a public port that can be reached
from Arexx-programs under the name MEGAED, as in:

address MEGAED

From within an Arexx-program, it's then possible to issue all
MegaEd MacroLanguage commands as discussed in chapter 5 to the editor.
Note that to use MegaEd with Arexx, either you own a machine with
Kick 2.x, or you have to buy the Arexx-software seperately.

To issue short commands to the ed from, for example a shell, use
the Arexx dos-command 'rx' as in

rx "address MEGAED; TOP; WRITE Arexx-test"

this command searches for a Arexx-port named MEGAED, then issues
those two commands to the ed.

Better even, write a complete program in "a" texted, (refer to your
Arexx-manual for details) and then let Arexx run the whole program.
for example, write a program like this:

/* Send MegaEd-host commands from macro program */

address MEGAED

TOP
do i=1 to 10
  INSERT 'I now insert line ' i ' into the buffer'
end
WRITE 'all done'


Both the Arexx language and the MegaEd macro language are not case
sensitive, but for the sake of the distinction:
Arexx-commands are written in lowercase, those will be interpreted
by the resident process, uppercase commands are directly forwarded
to the host (MegaEd). Note that Arexx-expressions as 'i' in the
INSERT statement will first be evaluated by Arexx before being send.
Now save this program to your REXX: directory as test.rexx and run
it from the shell with:

rx test

All MegaEd-commands can be runned in programs just like that, but only
three of them can give returnvalues back to the macroprogram, in the
standard Arexx-variable 'rc', those are MAXLINE, MAXCURSOR and DELCHAR.
The command 'RET' fills rc with a returnvalue.
When any other command returns anything, this is a sign something
went wrong. The following sample Arexx-program isn't very usefull,
however, it demonstrates clearly how to use returnvalues, and how
to gain access to every byte in the MegaEd buffer from within a
macro program:


/* This Arexx program will, as test, substitute all uppercase
   letters to lowercase and lowercase to Uppercase                             */

address MEGAED
options failat 10000      /* we don't want to bothered by error messages */

MAXLINE; RET; maxl=rc     /* get the size of the buffer in 'maxl'        */

/* NOREFRESH */           /* (add this command to speed up execution)    */

do i=1 to maxl
  LINE i
  MAXCURSOR; RET; maxc=rc /* use all chars of this line                  */
  do j=1 to maxc
    CURSOR j
    DELCHAR; RET; ch=rc
    if (ch>96)&(ch<123) then ch=ch-32
    else if (ch>64)&(ch<91) then ch=ch+32
    INSCHARS '#' ch       /* insert with asciivalue                      */
  end j
end i
WRITE Substitution done.

/* REFRESH */



No function has been implemented to run Arexx programs direct from
the editor, but can be done anyhow by adding the following line
to your S:MegaEd.Startup:

DEF 10 BACK; SAVE ram:x.rexx; EXE rx ram:x; FRONT

Pressing F10 will then execute the Arexx-program current in buffer.


------------------------------------------------------------------------
                           7. SPECIAL FEATURES
------------------------------------------------------------------------

Here we discuss functions in the 'Special' menu.

Make Program:
Enables you to write a MegaEd macroprogram directly in the editor: the
program can consist of multiple commands, being executed when the
appropriate function key is pressed. Arexx command are not supported in
macro's. For example, you would want to write a macro, that deletes
the third character on the current line (let's say because you're editing
a text that's malformatted that way): Select Special/Make Program,
then, press for example F1, and enter:

CURSOR 3; DELCHAR

Now pressing F1 will obtain the desired result.

Run Startup:
This will re-execute the file S:MegaEd.Startup, maybe because you just
edited that file, and don't want to leave the program to use the new
preferences, or you just want to undo the changes you made to the Settings.
For an example of an startup file see chapter 5.

Memory:
Shows available CHIP, FAST and Editor memory.

Toggle Title:
Replaces the MegaEd logo with a normal title and vice versa, just incase
you want to pull the screen up and down often, or just don't like the logo
and the custom 'back' gadget.

Program Check:
Checks for the bracket and quote structure of your sourcecode and displays
the amount of brackets found for each type {}[]()'"

Statistical infos:
shows amount of linefeeds, normal ascii chars etc. in your text

Open MML console:
will open a console on the workbench, where all output of Arexx etc.
is copied for a better overview

Read commands:
shows a prompt in the console, enabling you to type MML command directly.
for example, type:

> INSERT hi folks!

when returning to the ed, you will notice the text was inserted at
the cursor.

Record Keymacro:
will record all key and menu/mouse events to a seperate buffer until
Record Keymacro is reselected

Play keymacro:
processes all key/mouse/menu events recorded with Record Keymacro just
as if they were entered by you. This allows for flexible correction
of texts and execution repetive tasks.

Toggle linedisplay:
have linenumbers displayed.


------------------------------------------------------------------------
                           8. TROUBLE SHOOTING
------------------------------------------------------------------------

While on the whole MegaEd is a reliable and powerfull program, some bad
points about it are also known, and it's best you know about them.

First, MegaEd was programmed with a hardcoded limit on the editorbuffer
size (that is: the buffersize can be changed only before compilation),
which is currently some 75K. Problems threrefore may occur when loading
or editing texts that come close that limit. It's recommended NOT to use
MegaEd for sizy texts (>70K). The editor may, as you come near that limit
warn you with warnings of the type 'Could not load/ Editor buffer full/
You'd better save this text'. From that point on it's not wise to
continue with that text. Save it!

Second, you may sometimes be confronted with an error message of the type:
'somehow ... etc'. This is the case when a internal error occurred, but
the editor could stop itself from crashing. Sometimes when receiving this
error it's nothing severe and you could work on for hours, but it also
could be your last chance of saving before the program realy crashes.

However, above bad points seldom occur, and mostly don't appear to be
a problem, but it's better to count with them. When you, MegaEd, or
another program causes a guru, MegaEd will display the type of guru,
the number, and allow you to save the current buffer if you wish to
do so. Then, if it wasn't a heavy guru, you may work on.

note: MegaEd will not work properly if you are low on memory,
it eats approx. 300K of your freemem (of witch some 70K chip,
depending on if you run interlace, pal/ntsc etc.).


------------------------------------------------------------------------
                          9. ADDITIONAL INFO'S
------------------------------------------------------------------------

MegaEd was developed over the course of more than 1 year, and did circulate
as demo versions of MegaEd 1.0, 1.2 and 1.3. MegaEd was written in a
cooperation between Gfa-basic and Assembly, and it's now released in a
full 1.5i version as Public Domain, probably on Fish. Source is not
in the distribution, because it's undocumented, and contains inline
assembly routines just about everywhere. If, however, you can convince
me that it would be of good use to you, i'd be happy to think about it. *:)

Special thanx go to: Raymond Hoving for suggestions, beta-testing
and moral support.

Speziel für die deutche leute: schade, aber es gibt keine deutche
anleitung, und sicher keine deutche benutzerfürung. Aber bitte trösten
sie sich met dem gedanken, auch die leute die english als muttersprache
haben, haben sicherlich schwierigkeiten das program zu verstehen.

Needless to say, but: MegaEd may be copied and used freely as
long as the MegaEd.doc is with it, provided no modifications are made
to either the doc or the executable. For spreading on (pd) disk series
other than fish the usual PD-restictions apply: the package is distributed
as a whole, no profitable charges for copying etc. I will personally
RemHead() and AbortIO() those 'Pd-Distributors' that sell this program
for more than a copy-fee.

donations are welcome but certainly not obligatory.
suggestions, bug reports (only if you have to ...), the usual stuff:

         Wouter van Oortmerssen ($#%!)
         Levendaal 87
         2311 JG  Leiden
         HOLLAND

Or even better:

         [e-mail]